Issue #42: Engine-to-Integrator Error Contract

Context

The LearningEngine silently overrides integrator decisions when post-decision failures occur (engine.py:279-283). More broadly, VRE lacks a consistent error contract — many errors propagate as raw ValueError or untyped exceptions, making it hard for integrators to handle them programmatically.

Principle: VRE's responsibility is to roll back any in-memory mutations and re-raise errors with clear, typed exceptions. Integrators decide recovery strategy. VRE does not make recovery decisions on behalf of integrators.

Guard decorator: Unhandled exceptions propagating out of vre_guard is acceptable — the integrator wraps the decorated function call in their own error handling.

Part 1: Error Hierarchy — new src/vre/core/errors.py

Dedicated module for the exception hierarchy. Keeps models.py focused on domain models.

VREError (base for all VRE exceptions)
├── GraphError                          # any graph backend failure (reads + writes)
│   └── PersistenceError                # write-specific failures (save, delete)
├── GraphIntegrityError
│   └── CyclicRelationshipError         # re-parented from ValueError
├── HydrationError                      # JSON/data corruption on read
├── ResolutionError                     # concept/name resolution failures
└── CandidateValidationError            # invalid candidate fields in learning

• CyclicRelationshipError moves from core/models.py to core/errors.py. Clean break — no re-export from models.py.
• Re-parented from ValueError to GraphIntegrityError(VREError). Breaking change — acceptable.
• All existing imports update to from vre.core.errors import CyclicRelationshipError (or from vre import CyclicRelationshipError).

Part 2: Fix the Silent Override

File: src/vre/learning/engine.py:279-283

# Before — silent override:
try:
    self._repo.save_primitive(source)
except CyclicRelationshipError:
    depth_obj.relata.remove(new_relatum)
    return CandidateDecision.SKIPPED

# After — rollback + re-raise:
try:
    self._repo.save_primitive(source)
except CyclicRelationshipError:
    depth_obj.relata.remove(new_relatum)  # engine's cleanup responsibility
    raise                                  # integrator's decision

Exception propagates through learn_at → learn_all → integrator. The with callback: context manager ensures __exit__ fires for cleanup.

Part 3: Wrap Critical Sections

3a. Repository boundary — Neo4j (src/vre/core/graph.py)

Wrap all public methods so integrators never see raw Neo4j exceptions. Use GraphError for reads, PersistenceError for writes:

3b. Hydration (src/vre/core/graph.py)

Wrap _hydrate_primitive with HydrationError for JSON/data corruption.

3c. Concept resolution (src/vre/core/grounding/resolver.py)

Replace RuntimeError with ResolutionError for missing spaCy model.

3d. Learning engine validation (src/vre/learning/engine.py)

Replace raw ValueError with CandidateValidationError in all _persist_* methods, _resolve_name_to_id, and learn_at.

3e. Policy callback resolution (src/vre/core/policy/models.py)

Wrap resolve_callback() with VREError for ImportError/AttributeError.

3f. Cardinality — safe default on bad input

Default to None on unknown cardinality. Update the gate to fire all policies when cardinality is unknown — if we can't determine cardinality, we can't justify skipping any policy.